docs: Unify docs around incremental operations

Sync up the wording around incremental filtering
and sorting to be more similar.

diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 52d3c860d918b955e1b53caf4b3df8269e5a0935..9d943fb2aed06ebea4784ba5e23c7ace7dd159b3 100644 (file)
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -786,6 +786,9 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental filtering is disabled.
+ *
+ * See gtk_filter_list_model_get_pending() for progress information
+ * about an ongoing incremental filtering operation.
  **/
 void
 gtk_filter_list_model_set_incremental (GtkFilterListModel *self,
@@ -837,8 +840,6 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *
  * Returns the number of items that have not been filtered yet.
  *
- * When incremental filtering is not enabled, this always returns 0.
- *
  * You can use this value to check if @self is busy filtering by
  * comparing the return value to 0 or you can compute the percentage
  * of the filter remaining by dividing the return value by the total
@@ -850,6 +851,9 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *   percentage = pending / (double) g_list_model_get_n_items (model);
  * ]|
  *
+ * If no filter operation is ongoing - in particular when
+ * #GtkFilterListModel:incremental is %FALSE - this function returns 0.
+ *
  * Returns: The number of items not yet filtered
  **/
 guint

diff --git a/gtk/gtksortlistmodel.c b/gtk/gtksortlistmodel.c
index 24c2b5271d513d8e9c6cd8d5696c810478ce17d4..8f758d46cfbec7ff3a7856e4c130c417c2efd26f 100644 (file)
--- a/gtk/gtksortlistmodel.c
+++ b/gtk/gtksortlistmodel.c
@@ -61,6 +61,10 @@
  * #GtkSortListModel is a list model that takes a list model and
  * sorts its elements according to a #GtkSorter.
  *
+ * The model can be set up to do incremental sorting, so that
+ * sorting long lists doesn't block the UI. See
+ * gtk_sort_list_model_set_incremental() for details.
+ *
  * #GtkSortListModel is a generic model and because of that it
  * cannot take advantage of any external knowledge when sorting.
  * If you run into performance issues with #GtkSortListModel, it
@@ -978,6 +982,9 @@ gtk_sort_list_model_get_sorter (GtkSortListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental sorting is disabled.
+ *
+ * See gtk_sort_list_model_get_pending() for progress information
+ * about an ongoing incremental sorting operation.
  */
 void
 gtk_sort_list_model_set_incremental (GtkSortListModel *self,
@@ -1032,8 +1039,9 @@ gtk_sort_list_model_get_incremental (GtkSortListModel *self)
  *
  * If you want to estimate the progress, you can use code like this:
  * |[<!-- language="C" -->
- * double progress = 1.0 - (double) gtk_sort_list_model_get_pending (self) 
- *                         / MAX (1, g_list_model_get_n_items (G_LIST_MODEL (sort)));
+ *   pending = gtk_sort_list_model_get_pending (self);
+ *   model = gtk_sort_list_model_get_model (self);
+ *   progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
  * ]|
  *
  * If no sort operation is ongoing - in particular when